@codeyam-editor/codeyam-editor 0.1.6 → 0.1.7

package/npm/cloud.js

@@ -105,6 +105,10 @@ const {
 // edit (the invisible-VM gap improve38 closes). `readRoster` enumerates the
 // fleet for `reconcile-ingress`.
 const { addToRoster, readRoster } = require("./fleet-roster");
+// Tells a docker container-name conflict (a concurrent run already started this
+// container) apart from a real `docker compose up -d` failure, so the abort path
+// can converge instead of escalating to instance deletion.
+const { classifyComposeUpFailure } = require("./compose-conflict");
 
 // =============================================================================
 // Pure helpers — every export here is unit-tested in cloud.test.js without
@@ -845,6 +849,79 @@ function parseEditorComposeState(stdout) {
   return null;
 }
 
+/** Decide whether `cloud:up`'s abort handler may delete the instance it is
+ *  unwinding. Pure `{ createdThisRun, containerUp, rostered, probeInconclusive }
+ *  → 'delete' | 'keep'`, matching the `reapVerdict` / `reattachVerdict` /
+ *  `reconcileRosteredVm` pattern in npm/fleet-cleanup.js, so the whole matrix is
+ *  exhaustively testable without a VM.
+ *
+ *  `createdThisRun` stays a NECESSARY condition — never delete an instance this
+ *  run did not create — but 2026-08-07 proved it is not SUFFICIENT. It answers
+ *  "did I create this?", not "is it safe to destroy?", and in a concurrent
+ *  provision race the losing run legitimately owns the flag while the winner has
+ *  already brought the VM up and rostered it. Deleting there destroyed VM-4 and
+ *  VM-5. So authorization also requires CURRENT-STATE evidence that the VM is
+ *  out of service:
+ *
+ *  - `containerUp` — the editor container is running (per the compose-ps probe).
+ *    A VM serving an editor is in use by definition.
+ *  - `rostered` — the VM is in the fleet roster, the operator-visible source of
+ *    truth. Note this is true whether the winning run or THIS run rostered it;
+ *    either way the VM is visible in the dashboard and removable in one command,
+ *    so it is not the silent orphan teardown exists to prevent.
+ *  - `probeInconclusive` — liveness could not be determined. This must fail
+ *    SAFE: a failing probe is how we reach the abort handler in the first place,
+ *    so it can never count as evidence the VM is dead. An orphan costs one
+ *    `npm run cloud:destroy`; a wrong delete costs a 15-40 minute rebuild plus
+ *    any unpushed work on the VM. */
+function abortTeardownDecision({ createdThisRun, containerUp, rostered, probeInconclusive } = {}) {
+  if (!createdThisRun) return "keep";
+  if (probeInconclusive) return "keep";
+  if (containerUp) return "keep";
+  if (rostered) return "keep";
+  return "delete";
+}
+
+/** Gather the CURRENT-STATE inputs {@link abortTeardownDecision} needs, so the
+ *  abort handler reads gather → decide → act instead of inlining probes among
+ *  the delete calls.
+ *
+ *  Only runs the probes when `createdThisRun` is true — the decision is `keep`
+ *  regardless otherwise, and an abort path should not spend SSH round trips
+ *  proving something it already knows. In that case it returns the
+ *  probe-inconclusive shape, which is the safe default at every layer.
+ *
+ *  Both lookups are wrapped: a throwing probe or an unreadable roster must fail
+ *  SAFE (toward `keep`), never take a second exception path into the delete.
+ *  `deps` is injectable so the matrix is unit-tested without a VM. */
+function probeAbortTeardownState(cfg, createdThisRun, deps = {}) {
+  if (!createdThisRun) {
+    return { containerUp: false, rostered: false, probeInconclusive: true };
+  }
+  const probe = deps.probeEditorComposeState || probeEditorComposeState;
+  const roster = deps.readRoster || readRoster;
+  const resolveVm = deps.resolveFleetVmNumber || resolveFleetVmNumber;
+  const log = deps.log || ((m) => console.error(m));
+
+  let liveness = { state: null, inconclusive: true };
+  try {
+    liveness = probe(cfg);
+  } catch (e) {
+    log(`  (liveness probe failed: ${e && e.message})`);
+  }
+  let rostered = false;
+  try {
+    const vm = resolveVm(cfg.instanceName);
+    rostered = vm != null && (roster() || []).includes(vm);
+  } catch { /* unreadable roster — treated as not-rostered; liveness still guards */ }
+
+  return {
+    containerUp: liveness.state === "running",
+    rostered,
+    probeInconclusive: liveness.inconclusive,
+  };
+}
+
 /** Translate one of the wrapper's verbs into the exact `gcloud` argv. The
  *  switch's job is to keep every per-verb command shape in one reviewable
  *  place — tests assert the arrays without ever spawning a process. */
@@ -2049,20 +2126,65 @@ async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   }
 }
 
-async function ensureEditorContainerUp(cfg) {
+/** Run the compose-ps liveness probe over SSH and report BOTH the editor
+ *  service's state and whether the probe itself could be trusted.
+ *
+ *  The `|| true` keeps the remote pipeline's exit status 0 whenever SSH itself
+ *  worked, so a non-zero `status` means the transport failed (auth/SSH/IAP) —
+ *  not that the container is down. Callers that must fail safe (the abort
+ *  teardown) need that distinction; `parseEditorComposeState` alone collapses
+ *  "no container" and "could not ask" into the same `null`.
+ *
+ *  Returns `{ state, inconclusive }` where `state` is the compose `State` string
+ *  (`"running"`, `"exited"`, …) or null when the service is absent, and
+ *  `inconclusive` is true only for a transport failure. */
+function probeEditorComposeState(cfg) {
   const repoName = resolveProject(cfg).name;
-  // -f docker-compose.cloud.yml everywhere: the editor repo's own
-  // docker-compose.yml does `build: .` from source and would shadow the
-  // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
   const composeCmd = `docker compose -f docker-compose.cloud.yml`;
-  console.error("Checking editor container state...");
   const probe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} && ${composeCmd} ps --format json 2>/dev/null || true`,
+      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
     }),
     { stdio: ["ignore", "pipe", "ignore"] },
   );
-  if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
+  if (probe.status !== 0) {
+    return { state: null, inconclusive: true };
+  }
+  return { state: parseEditorComposeState(probe.stdout), inconclusive: false };
+}
+
+/** Poll {@link probeEditorComposeState} until the editor service reads
+ *  `running`, returning true as soon as it does. Used to close the TOCTOU window
+ *  after a container-name conflict: the winning run may still be inside
+ *  `Creating`/`Created` when the conflict surfaces, so a single immediate probe
+ *  can under-read and report a healthy container as absent.
+ *
+ *  Deliberately short (default ~30s): this is not the multi-minute first-boot
+ *  budget `waitForContainerRunning` grants, it is the tail of a start that
+ *  another process has already begun. `sleepFn` and `probeFn` are injectable so
+ *  a unit test drives the whole loop with neither wall-clock delay nor a VM. */
+async function waitForEditorComposeRunning(cfg, { attempts = 6, delayMs = 5000, sleepFn, probeFn } = {}) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const probe = probeFn || probeEditorComposeState;
+  for (let i = 0; i < attempts; i++) {
+    if (probe(cfg).state === "running") {
+      return true;
+    }
+    if (i < attempts - 1) {
+      await sleep(delayMs);
+    }
+  }
+  return false;
+}
+
+async function ensureEditorContainerUp(cfg) {
+  const repoName = resolveProject(cfg).name;
+  // -f docker-compose.cloud.yml everywhere: the editor repo's own
+  // docker-compose.yml does `build: .` from source and would shadow the
+  // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  console.error("Checking editor container state...");
+  if (probeEditorComposeState(cfg).state === "running") {
     console.error("  ✓ editor container is already running");
     // containerStarted: the container is confirmed up, so the CLI install runs
     // its POST-start path with no wait — see the precondition on ensureAgentCliInstalled.
@@ -2070,14 +2192,47 @@ async function ensureEditorContainerUp(cfg) {
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
+  // CAPTURE rather than `stdio: "inherit"`: the daemon writes its container-name
+  // conflict to stderr, and with "inherit" that text went straight to our parent
+  // and was never observable here — so the conflict could not be told apart from
+  // a real failure (the 2026-08-07 VM-4/VM-5 delete). spawnSync cannot both
+  // stream and capture, so the operator's view is preserved by echoing the
+  // captured streams immediately below instead of live. Do NOT revert this to
+  // "inherit"; classification depends on it.
   const up = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
       command: `cd ~/projects/${repoName} && ${composeCmd} up -d`,
     }),
-    { stdio: "inherit" },
+    { stdio: ["ignore", "pipe", "pipe"] },
   );
+  if (up.stdout) process.stderr.write(up.stdout);
+  if (up.stderr) process.stderr.write(up.stderr);
   if (up.status !== 0) {
-    throw new Error("docker compose up -d failed on the VM");
+    const verdict = classifyComposeUpFailure({ status: up.status, stderr: `${up.stderr || ""}\n${up.stdout || ""}` });
+    if (verdict !== "name-conflict") {
+      throw new Error("docker compose up -d failed on the VM");
+    }
+    // A name conflict means a concurrent run already created this container —
+    // the goal we were about to pursue is being reached by someone else. Confirm
+    // that positively before converging: a conflict whose container never
+    // reaches `running` (e.g. a stale STOPPED container squatting the name) is a
+    // genuine problem and must still fail loudly, or convergence becomes a
+    // catch-all that papers over real breakage.
+    console.error(
+      "  a concurrent run already created the editor container — confirming it reaches running...",
+    );
+    if (!(await waitForEditorComposeRunning(cfg))) {
+      throw new Error(
+        "docker compose up -d hit a container-name conflict on the VM, but the conflicting " +
+          "container never reached running (a stale stopped container may be holding the name). " +
+          `Inspect with: gcloud compute ssh ${cfg.instanceName} --command 'cd ~/projects/${repoName} && ${composeCmd} ps -a'`,
+      );
+    }
+    console.error("  ✓ editor container is running (started by a concurrent run)");
+    // containerStarted: the container is confirmed up — same post-start contract
+    // as the already-running short-circuit above.
+    await ensureAgentCliInstalled(cfg, { containerStarted: true });
+    return;
   }
   // containerStarted: `up -d` returned 0, so the CLI install is legitimately a
   // post-start step. A brief wait-for-running here (slow boot settling) is
@@ -2093,18 +2248,10 @@ async function ensureEditorContainerUp(cfg) {
 // success. This throws (non-zero exit) when the editor service isn't
 // `running`, converting a silent partial provision into a loud, actionable
 // failure the operator (and the dashboard's fail-fast-on-nonzero path) can act
-// on. The `|| true` keeps the probe's exit status 0 so the real signal is the
-// parsed compose state, not the SSH/cd exit code.
+// on. An inconclusive probe is not "running" here — a terminal gate must have
+// positive evidence, and the caller's job is to fail loudly without it.
 async function assertEditorContainerRunning(cfg) {
-  const repoName = resolveProject(cfg).name;
-  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
-  const probe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  if (!(probe.status === 0 && parseEditorComposeState(probe.stdout) === "running")) {
+  if (probeEditorComposeState(cfg).state !== "running") {
     throw new Error(
       `provisioning incomplete: editor container is not running on ${cfg.instanceName} ` +
         `(no /workspace or container). Re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
@@ -4122,7 +4269,27 @@ async function cmdUp(args, projectDir = rootDir) {
       );
     }
   } catch (err) {
-    if (createdThisRun) {
+    // `createdThisRun` alone MUST NOT authorize deletion. Gather what state the
+    // VM is in right now, then let the pure decision rule — see
+    // abortTeardownDecision's doc comment for why each input is load-bearing.
+    const state = probeAbortTeardownState(cfg, createdThisRun);
+    const verdict = abortTeardownDecision({ createdThisRun, ...state });
+    if (createdThisRun && verdict === "keep") {
+      // Deliberately loud and specific. The old blanket "tearing down the VM
+      // cloud:up created this run (no orphan left behind)" was actively
+      // misleading here — it asserted no orphan while deleting a working VM.
+      const why = state.probeInconclusive
+        ? "its liveness could not be confirmed (probe failed), and an unconfirmed VM is never deleted"
+        : state.containerUp
+          ? "its editor container is RUNNING — another run brought it up"
+          : "it is in the fleet roster and visible to the dashboard";
+      console.error(
+        `✗ provisioning aborted — the VM ${cfg.instanceName} was LEFT IN PLACE because ${why}.\n` +
+          `  This run created the instance, but that alone does not authorize deleting a VM that is in service.\n` +
+          `  If it really should go, remove it deliberately: npm run cloud:destroy`,
+      );
+    }
+    if (verdict === "delete") {
       console.error(
         `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
       );
@@ -4304,14 +4471,7 @@ async function cmdStatus(args, projectDir = rootDir) {
   const imgStatus = String(imgProbe.stdout || "").trim() || "?";
   console.error(`  image:            ${imgStatus}`);
 
-  const repoName = resolveProject(cfg).name;
-  const containerProbe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} 2>/dev/null && docker compose -f docker-compose.cloud.yml ps --format json 2>/dev/null || echo`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  const containerStatus = parseEditorComposeState(containerProbe.stdout) || "missing";
+  const containerStatus = probeEditorComposeState(cfg).state || "missing";
   console.error(`  editor container: ${containerStatus}`);
 
   const appPort = await readVmAppPort(cfg);
@@ -5058,6 +5218,9 @@ module.exports = {
   assertAgentCliInstalled,
   probeContainerRunning,
   probeContainerState,
+  waitForEditorComposeRunning,
+  abortTeardownDecision,
+  probeAbortTeardownState,
   probeAgentBinaryInstalled,
   waitForContainerRunning,
   KNOWN_FLAGS,

package/npm/compose-conflict.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// npm/compose-conflict.js — classify a failed `docker compose up -d` on a fleet
+// VM, so `cloud:up` can tell "another run beat me to this container" apart from
+// "provisioning genuinely broke".
+//
+// Why this exists: on 2026-08-07 two concurrent `cloud:up` runs raced to start
+// the editor container on one fresh VM. The loser's `up -d` exited non-zero with
+// the docker daemon's container-name conflict, `cloud.js` flattened that into a
+// generic "docker compose up -d failed on the VM", and the abort handler
+// escalated it all the way to deleting a VM the winner had already brought up
+// and rostered. A name conflict is the opposite of a failure — it is proof the
+// shared goal (container running) was reached by someone else.
+//
+// Matching a daemon error string is exactly the kind of thing that rots when
+// docker rephrases it, so it lives here as a named, unit-tested function with
+// the real observed message pinned as a fixture — not as an inline regex at the
+// call site.
+
+// The stable fragments of the daemon's conflict message. The container id and
+// name vary per run and docker's exact phrasing has changed across versions, so
+// we require all three fragments rather than the whole sentence. Observed
+// verbatim in the VM-4 add log:
+//
+//   Error response from daemon: Conflict. The container name
+//   "/codeyam-editor-editor-1" is already in use by container "c9d448c6…".
+//   You have to remove (or rename) that container to be able to reuse that name.
+//
+// Compose emits it twice (once prefixed `service:editor:1`, once bare) and
+// interleaves its own progress lines, so the match is substring-based over the
+// whole captured stream rather than line- or anchor-based.
+const NAME_CONFLICT_FRAGMENTS = [/\bConflict\./i, /container name/i, /is already in use/i];
+
+/** Classify the outcome of `docker compose up -d`.
+ *
+ *  Returns one of:
+ *  - `'ok'` — the command succeeded; there is no failure to classify. Guards
+ *    against a caller that classifies unconditionally, so a zero status can
+ *    never be read as a conflict.
+ *  - `'name-conflict'` — the daemon refused because a container of that name
+ *    already exists, i.e. a concurrent run already started it. The caller
+ *    re-probes for a running container and converges instead of throwing.
+ *  - `'failed'` — anything else. Existing behavior: a real provisioning
+ *    failure.
+ *
+ *  Pure: `{ status, stderr } → tag`, with no I/O, so the whole matrix is
+ *  testable without a VM. `stderr` may be null/undefined (the pre-fix call site
+ *  captured nothing), which classifies as `'failed'` — the conservative
+ *  direction, since converging requires positive evidence of a conflict. */
+function classifyComposeUpFailure({ status, stderr } = {}) {
+  if (status === 0) return 'ok';
+  const text = String(stderr == null ? '' : stderr);
+  if (NAME_CONFLICT_FRAGMENTS.every((re) => re.test(text))) {
+    return 'name-conflict';
+  }
+  return 'failed';
+}
+
+module.exports = { classifyComposeUpFailure };

package/npm/fleet-add-failure.js

@@ -96,6 +96,67 @@ function transcriptRostered(logTail) {
   return parseRosterMarkers(String(logTail || '')).length > 0;
 }
 
+// The categories that describe an add whose outcome is NOT yet proven bad — the
+// calm, in-flight side of the classifier. `converging` is a rostered box whose
+// ingress is still wiring; `verifying` is the residue: no failure signature
+// matched and nothing durable proves the VM is dead. Both render a calm card and
+// neither may use the word "failed". Consumed by holdConvergingBadge and by
+// deriveStatus (server.js) to pick the matching calm status.
+const CALM_ADD_CATEGORIES = new Set(['converging', 'verifying']);
+
+// Is a non-zero add outcome CORROBORATED by a durable fact — i.e. do we have
+// positive proof of death, rather than merely an absence of proof of life?
+//
+// This is the conjunction that gates the red `unknown` verdict. Before it, the
+// classifier's fallthrough treated "no recognized success signature" as failure,
+// so "we don't know" rendered as a terminal red "Add failed" telling the operator
+// to destroy a VM whose container was Up and whose editor answered /api/health
+// 200 (VM-4, 2026-07-31). Red now requires BOTH halves:
+//
+//   1. A non-zero exit code. A *missing* code is not proof of death — today it
+//      usually means the wrapper was signal-killed while its provision ran on,
+//      which is exactly the case that was misreading as failure. `null`,
+//      `undefined`, a non-integer, and 0 all fail this half.
+//   2. At least one durable corroborating fact:
+//        - `instanceAlive === false`   GCP says the instance is gone.
+//        - `containerHealthy === false` the in-VM editor was probed and is not
+//          answering — the box exists but never came up.
+//        - `wiringDeadlineBlown`       the wire-add-tail gave up (the failed
+//          marker is the tail's own honest deadline signal).
+//
+// Every fact is TRI-STATE on purpose: `undefined`/`null` means "not probed" and
+// corroborates nothing. Only an explicit `false` counts, so an unprobed VM can
+// never be escalated to red by absence of evidence.
+function addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
+  const code = exitCode == null ? NaN : Number(exitCode);
+  if (!Number.isInteger(code) || code === 0) return false;
+  return instanceAlive === false || containerHealthy === false || !!wiringDeadlineBlown;
+}
+
+// Resolve the two independent health signals into the single tri-state
+// `containerHealthy` fact addFailureCorroborated consumes. Pure so the precedence
+// — which decides whether a VM can be escalated to red — is unit-tested; the
+// server (addFailureFacts) supplies the live signals.
+//
+//   reachable    the editor answered over the LB.
+//   inVmHealthy  the STRAND_PROBE /api/health read from INSIDE the container.
+//
+// LB reachability wins when present: it is the stronger witness (it proves the
+// whole URL→ingress→backend path, not just the process). Otherwise the in-VM
+// witness answers — this is the still-wiring case, where the LB necessarily
+// cannot see a VM whose ingress is what we are waiting on, yet the editor itself
+// is demonstrably up.
+//
+// Returns `null` when NEITHER signal was gathered. That is the load-bearing case:
+// an unprobed VM must corroborate nothing, so it can never be escalated to red by
+// absence of evidence. `false` is reserved for a VM that was genuinely probed and
+// did not answer.
+function containerHealthWitness({ reachable, inVmHealthy } = {}) {
+  if (reachable) return true;
+  if (inVmHealthy != null) return !!inVmHealthy;
+  return null;
+}
+
 // Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
 // can never drift from the category.
 function buildFailureVerdict(category, headline, recovery, extra) {
@@ -108,7 +169,16 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 //
 //   logTail   the last lines of the provision transcript (string; '' when the
 //             log was unreadable — must never throw)
-//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//   exitCode  the provision's exit code (number; used for signal-kill detection
+//             and as the first half of the proof-of-death conjunction)
+//
+// The remaining inputs are the durable facts the server gathers (the module
+// stays pure — it never probes). All are tri-state; omit any that was not
+// probed and it corroborates nothing. See addFailureCorroborated.
+//
+//   instanceAlive        does GCP still list the instance?
+//   containerHealthy     did the in-VM editor answer /api/health?
+//   wiringDeadlineBlown  did the add-time wire tail drop its failed marker?
 //
 // Returns { category, headline, recovery, retryable, files? }.
 //
@@ -118,7 +188,7 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 // signature is therefore tested BEFORE the generic cloud-up-failed signature, or
 // a retryable drift would misclassify as a non-retryable cloud:up failure and the
 // operator would lose the safe one-click recovery.
-function classifyAddFailure({ logTail, exitCode } = {}) {
+function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
   const log = String(logTail || '');
 
   // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
@@ -218,9 +288,34 @@ function classifyAddFailure({ logTail, exitCode } = {}) {
       'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
   }
 
-  // 9. unknown — fallback. Never invite an unproven retry.
-  return buildFailureVerdict('unknown', 'Add failed',
-    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+  // 9. The residue: no failure signature above matched. The polarity here is
+  //    INVERTED from the original design. It used to read "no recognized success
+  //    signature ⇒ failed", which made red the DEFAULT for "we don't know" — so a
+  //    VM whose container was Up and whose editor answered /api/health 200 got a
+  //    terminal red "Add failed" card advising the operator to destroy it (VM-4,
+  //    2026-07-31; the wrapper had been killed mid-flight, so its transcript was
+  //    truncated before CY_ROSTER and it never reached the `converging` arm above).
+  //
+  //    Red now requires positive proof of death, and everything else is in-flight:
+  //
+  //    9a. unknown — a non-zero exit CORROBORATED by a durable fact (see
+  //        addFailureCorroborated). The box is provably dead or provably never
+  //        came up, so the loud, terminal escalation is warranted and unchanged.
+  //        Still never invites an unproven retry.
+  if (addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown })) {
+    return buildFailureVerdict('unknown', 'Add failed',
+      'The add failed for an unclassified reason and the VM is confirmed dead or never came up — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+  }
+
+  //    9b. verifying — the honest default. No failure signature, and nothing
+  //        durable proves this VM is dead: it may still be provisioning or
+  //        wiring, and the ingress can keep propagating for minutes after the
+  //        wrapper is gone. Calm copy, transcript still one click away. NOT
+  //        retryable — nothing is proven about the box either way, so a one-click
+  //        retry could still duplicate a live GCP instance (the ADD_FAILURE_RETRYABLE
+  //        grounds are unchanged by this inversion).
+  return buildFailureVerdict('verifying', 'Add outcome unconfirmed',
+    'No failure signature was found in the transcript and nothing proves this VM is dead, so the add may still be converging — the ingress keeps propagating for minutes after the provision wrapper exits. Inspect the transcript below; reconcile this VM only if it is still unresolved past the wiring deadline.');
 }
 
 // Pure guard for the operator "Retry add" action: given a VM number and its
@@ -238,15 +333,29 @@ function canRetryAdd({ n, job } = {}) {
 }
 
 // Pure badge-hold predicate for deriveStatus (server.js): hold the calm in-flight
-// `add-converging` card — instead of the red add-failed — ONLY when the add was
-// classified `converging` AND its detached first-wiring is still in flight. Once
-// the wire-add-tail fails/deadlines (`addTailFailed`) or is gone (`addTailInflight`
-// false), or the category is anything else, return false so the caller falls
-// through to the red add-failed status — the operator-chosen escalation. Kept pure
-// (like canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
+// card — instead of the red add-failed — while the add is still converging.
+//
+// The hold used to require `addTailInflight`, i.e. that the detached wire-add-tail
+// PROCESS was still alive. That premise was wrong: the tail's exit says nothing
+// about LB convergence, because the EXTERNAL_MANAGED backend services keep
+// propagating for minutes afterwards. VM-4's backends were still being created at
+// 18:17-18:20Z, long after its job had been declared failed at 18:15Z — the tail
+// had exited, so the calm hold released and the card went red on a healthy VM.
+//
+// The hold is now driven by the question that actually matters: is this add still
+// converging, and has its wiring deadline genuinely blown? `wiringDeadlineBlown`
+// (the failed marker the tail drops when it gives up) stays the release signal —
+// tail liveness is no longer a requirement for calm, so the calm state survives
+// the multi-minute propagation window instead of ending at process exit.
+//
+// Both calm categories qualify (see CALM_ADD_CATEGORIES): a rostered box that is
+// still wiring, and the unproven residue. Any proven-failure category returns
+// false and falls through to the red add-failed status — the operator-chosen
+// escalation, which this predicate narrows but never softens. Kept pure (like
+// canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
 // live dashboard.
-function holdConvergingBadge({ category, addTailInflight, addTailFailed } = {}) {
-  return category === 'converging' && !!addTailInflight && !addTailFailed;
+function holdConvergingBadge({ category, wiringDeadlineBlown } = {}) {
+  return CALM_ADD_CATEGORIES.has(category) && !wiringDeadlineBlown;
 }
 
-module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, ADD_FAILURE_RETRYABLE };
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };